home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 23 / Amiga Format AFCD23 (Feb 1998, Issue 107).iso / -seriously_amiga- / shareware / programming / other / iff-rgfx / rgfx-chunks.doc < prev    next >
Text File  |  1997-12-12  |  9KB  |  276 lines
  1.  $VER: RGFX-Chunks.doc 1.2 (7.12.97)
  2.  
  3.  
  4.  A typical structure of a RGFX file (recommended) :
  5.  
  6.  
  7.      FORM-RGFX
  8.  
  9.        RGHD     Image Header
  10.        RSCM     Screenmode information
  11.        RCOL     Color and transparency information
  12.        RBOD     The Graphics itself
  13.  
  14.  
  15.      Additional (optional) chunks should appear somewhere
  16.      between RCOL and RBOD.
  17.  
  18.  
  19.  RGFX - Basic chunks
  20.  ===================
  21.  
  22.    RGHD - RawGfx Bitmap Header
  23.    ---------------------------
  24.    ** This one replaces BMHD
  25.  
  26. struct RGHD
  27. {
  28.  ULONG rgfx_LeftEdge;     /* (see BMHD)                               */
  29.  ULONG rgfx_TopEdge;      /* (see BMHD)                               */
  30.  ULONG rgfx_Width;        /* (see BMHD)                               */
  31.  ULONG rgfx_Height;       /* (see BMHD)                               */
  32.  ULONG rgfx_PageWidth;    /* (see BMHD)                               */
  33.  ULONG rgfx_PageHeight;   /* (see BMHD)                               */
  34.  
  35.  ULONG rgfx_Depth;        /* 1-8         for RMBT_BYTEPLANAR8,
  36.                              1-8         for RMBT_BYTECHUNKY8,
  37.                               24         for RMBT_3BYTERGB24          */
  38.  ULONG rgfx_PixelBits;    /* 1-8         for RMBT_BYTEPLANAR8,
  39.                                8         for RMBT_BYTECHUNKY8,
  40.                               24         for RMBT_3BYTERGB24          */
  41.  ULONG rgfx_BytesPerLine; /* (width+7)/8 for RMBT_BYTEPLANAR8,
  42.                               width      for RMBT_BYTECHUNKY8,
  43.                               width*3    for RMBT_3BYTERGB24          */
  44.  
  45.  ULONG rgfx_Compression;  /* RCMP_ type flag                          */
  46.  ULONG rgfx_XAspect;      /* (see BMHD)                               */
  47.  ULONG rgfx_YAspect;      /* (see BMHD)                               */
  48.  ULONG rgfx_BitMapType;   /* RBMT_ type flag                          */
  49. };
  50.  
  51.  
  52.  If you encounter unknown depth/pixelbits/bytesperline combinations,
  53.  then do reject these (future expansions). But so far, only use
  54.  the legally defined ones yourself ! Don't define own formats,
  55.  e.g. for 16 Bit or for BGR !
  56.  
  57.  
  58. #define RCMT_NOCOMPRESSION  (0L)
  59. #define RCMT_XPK            (1L)
  60.  
  61. #define RMBT_BYTEPLANAR8    (0L)   /* unaligned planar 8 bit bitmap */
  62. #define RMBT_BYTECHUNKY8    (1L)   /* unaligned chunky 8 bit bitmap */
  63. #define RMBT_3BYTERGB24     (2L)   /* 3-byte 24 bit RGB triples     */
  64.  
  65.  BYTEPLANAR8 data is similar to a regular bitmap (or an ABIT data chunk),
  66.  with the exeception, that no alignment, i.e. to word boundaries, does
  67.  take place - in general, we don't make use of alignment.
  68.  
  69.  
  70.    RSCM - RawGfx ScreenMode
  71.    ------------------------
  72.    ** This one replaces CAMG.
  73.  
  74.    The default setting is:
  75.  
  76.    rscm_AGA:  default screenmode
  77.    rscm_CGfx: INVALID_ID
  78.    rscm_P96:  INVALID_ID
  79.  
  80.    if ModeNotAvailable( rscm_P96 ) does return an error,
  81.    then try ModeNotAvailable( rscm_CGfx ) - on error,
  82.    then try ModeNotAvailable( rscm_AGA ).
  83.  
  84.    Use the first ID, which is available, otherwise compute
  85.    one yourself by using BestModeID()
  86.  
  87.  
  88.    Note: Since HAM modes only can be identified by their
  89.          ID, you should make sure, tht CGfx/P96 are set
  90.          to INVALID_ID and that AGA is OR'ed with HAM_KEY
  91.          for these modes.
  92.          For EHB, you should make sure, that the AGA viewmode
  93.          field is OR'ed with EXTRAHALFBRITE_KEY - if you want
  94.          to keep that feature with the graphics. Please also
  95.          see colormap notes for EHB.
  96.          (see <graphics/modeid.h>)
  97.  
  98. struct RSCM
  99. {
  100.  ULONG rscm_AGA;  /* 32 Bit AGA  Viewmode ID */
  101.  ULONG rscm_CGfx; /* 32 Bit CGfx Viewmode ID */
  102.  ULONG rscm_P96;  /* 32 Bit P96  Viewmode ID */
  103. };
  104.  
  105.  
  106.  
  107.    RCOL - RawGfx Colormap
  108.    ----------------------
  109.    ** This one replaces CMAP,
  110.  
  111.       Required with RMBT_BYTEPLANAR8 and RMBT_BYTECHUNKY8,
  112.       and optionally allowed with RMBT_3BYTERGB24 for use
  113.       as a dithering destination colormap.
  114.  
  115.       Stored are 256 byte triples in RGB format. Note, that
  116.       full-range values (0..255) have to be stored.
  117.  
  118.       Sample:   rcol_Colors[0][0]   = 0..255 red   value, color #0 (1st)
  119.                 rcol_Colors[0][1]   = 0..255 green value, color #0
  120.                 rcol_Colors[0][2]   = 0..255 blue  value, color #0
  121.                 ...
  122.                 rcol_Colors[255][0] = 0..255 red   value, color #255 (256th)
  123.                 rcol_Colors[255][1] = 0..255 green value, color #255
  124.                 rcol_Colors[255][2] = 0..255 blue  value, color #255
  125.  
  126.  
  127.       Unused entries should be filled with zeroes.
  128.  
  129. struct RCOL
  130. {
  131.  ULONG rcol_TransColor;      /* boolean: is there a transparent color ?  */
  132.  ULONG rcol_TransColorNum;   /* yes, it's number ... from the ones below */
  133.  UBYTE rcol_Colors[256][3];
  134. };
  135.  
  136.    Allowed boolean values:  TRUE (1L) and FALSE (0L)
  137.  
  138.    Note: With EHB mode, which e.g. uses 64 colors with only a 32 color
  139.          palette, you always should store the full color range within
  140.          the RCOL structure: if someone is going to display EHB pictures
  141.          on an RTG screen, he won't have to calculate the 'missing'
  142.          colors by himself.
  143.  
  144.  
  145.    RBOD - RawGfx Bitmap Body
  146.    -------------------------
  147.    ** This one replaces BODY
  148.  
  149.  May look like:
  150.  
  151. struct RBOD
  152. {
  153.  UBYTE rbod_XPK[3];     ** containing 'XPK'
  154.  UBYTE rbod_BitMap[];
  155. };
  156.  
  157.  Or simply:
  158.  
  159. struct RBOD
  160. {
  161.  UBYTE rbod_BitMap[];
  162. };
  163.  
  164.  This has not been defined as a union structure here, since some
  165.  compilers may add unrequested pad bytes to the structure.
  166.  
  167.  You should reference this chunk as an UBYTE array, only.
  168.  
  169.  
  170.  RGFX - Optional chunks
  171.  ======================
  172.  
  173.    RXYA - Viewable XY-Area
  174.    -----------------------
  175.    ** based on an idea by Peter Bornhall <bornhall@swipnet.se>
  176.  
  177.       It may be useful to specify a small "view area" fromout
  178.       a larger image, e.g. a 320x200 area inside a 2048x2048
  179.       image.
  180.  
  181. struct RXYA
  182. {
  183.  ULONG xy_LeftEdge;
  184.  ULONG xy_TopEdge;
  185.  ULONG xy_Width;
  186.  ULONG xy_Height;
  187. };
  188.  
  189.  
  190.    RXXX - Image Rating
  191.    -------------------
  192.    ** based on an idea by Peter Bornhall <bornhall@swipnet.se>
  193.  
  194.       Not all images may be suitable for any group of recepients.
  195.  
  196. struct RXXX
  197. {
  198.  ULONG xxx_Rating; /* e.g. for parents who want to control access */
  199. };
  200.  
  201. #define RXXX_HARMLESS          (0L) /* this image won't affect anyone        (e.g. cliparts)       */
  202. #define RXXX_PARENTAL_ADVISORY (1L) /* some people may feel offended by this (e.g. violent comics) */
  203. #define RXXX_OFFENSIVE         (2L) /* most people will feel offended by this (whatever)           */
  204.  
  205.  
  206.    RALH - Alpha Channel Header
  207.    ---------------------------
  208.    ** based on an idea by Marcel Offermans <M.Offermans@CBi.CentraalBeheer.NL>
  209.  
  210.       We support three different types of Alpha channels:
  211.  
  212.         - operating on a colormap (with upto 8 bit images only, and
  213.           only, if MORE than one color should be transparent, i.e.
  214.           when RCOL.rcol_TransColor does not suffice). Like with RCOL,
  215.           the supplied table should be sized for 256 colors always, thus
  216.           any unused entries should be set to zero (= fully transparent).
  217.  
  218.         - operating on separate pixels (with any bitdepth),
  219.           supplying a width*height area of 0..255 values for
  220.           each pixel (or component), where 0 means "fully transparent"
  221.           and 255 means "not transparent at all"
  222.  
  223.       We also allow to differ between "complete" transparency and
  224.       "color component specific" transparency, i.e. you either may apply
  225.       the transparency to the whole RGB value of the color/pixel OR to each one
  226.       of the RGB color components separately (which means 3 times as much data).
  227.       This works with colormaps as well as pixelmaps.
  228.  
  229.       Examples:   - transparent colormap, for whole color
  230.  
  231.                       256 entries, each one ranged 0..255
  232.                       [ size: 256 bytes ]
  233.  
  234.                   - transparent colormap, for color components
  235.  
  236.                       256 triple entries, means
  237.                       three sub entries ranged 0..255 (for R, G and B)
  238.                       [ size: 768 bytes ]
  239.  
  240.                   - transparent pixelmap, for whole 8/24 Bit pixels
  241.  
  242.                       <width> x <height> entries, each one
  243.                       ranged 0..255
  244.                       [ size: width x height ]
  245.  
  246.                   - transparent pixelmap, for RGB components 8/24 Bit pixels
  247.  
  248.                       <width> x <height> entries, means each pixel with
  249.                       three sub entries ranged 0..255 (for R, G and B)
  250.                       [ size: width x height x 3 ]
  251.  
  252.                       This may not be practical for most uses, since it
  253.                       will double the space needed for a 24 bit graphics
  254.                       and will need four times the space for a 8 bit graphics.
  255.  
  256.  
  257. struct RALH
  258. {
  259.  ULONG ralh_AlphaType;            /* the type of alpha channel - colormap (8 bit)    */
  260.                                   /* or pixelmap (8/24 bit)                          */
  261.  ULONG ralh_TransparencyType;     /* Completely or for a single component, only ?    */
  262. };
  263.  
  264. #define RALH_TYPE_PIXEL (0L)      /* 8/24 bit: (non)transparacy value for each pixel */
  265. #define RALH_TYPE_CMAP  (1L)      /* upto 8 Bit, only: supplies another colormap     */
  266.  
  267. #define RALH_TRANS_ALL       (0L) /* one 0.255 value for all components              */
  268. #define RALH_TRANS_COMPONENT (1L) /* one 0.255 value for each, separate component    */
  269.  
  270.  
  271.  RGFX - Other chunks
  272.  ===================
  273.  
  274.    - NAME, AUTH, ANNO and (C) chunks are allowed
  275.  
  276.